<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
<meta name="generator" content="Doxygen 1.8.3.1"/>
<title>procman: Deputies and Sheriffs</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script>
<link href="search/search.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="search/search.js"></script>
<script type="text/javascript">
  $(document).ready(function() { searchBox.OnSelectItem(0); });
</script>
<link href="doxygen.css" rel="stylesheet" type="text/css" />
</head>
<body>
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<div id="titlearea">
<table cellspacing="0" cellpadding="0">
 <tbody>
 <tr style="height: 56px;">
  <td style="padding-left: 0.5em;">
   <div id="projectname">procman
   </div>
  </td>
 </tr>
 </tbody>
</table>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.8.3.1 -->
<script type="text/javascript">
var searchBox = new SearchBox("searchBox", "search",false,'Search');
</script>
  <div id="navrow1" class="tabs">
    <ul class="tablist">
      <li><a href="index.html"><span>Main&#160;Page</span></a></li>
      <li><a href="modules.html"><span>Modules</span></a></li>
      <li><a href="annotated.html"><span>Python&#160;API</span></a></li>
      <li>
        <div id="MSearchBox" class="MSearchBoxInactive">
        <span class="left">
          <img id="MSearchSelect" src="search/mag_sel.png"
               onmouseover="return searchBox.OnSearchSelectShow()"
               onmouseout="return searchBox.OnSearchSelectHide()"
               alt=""/>
          <input type="text" id="MSearchField" value="Search" accesskey="S"
               onfocus="searchBox.OnSearchFieldFocus(true)" 
               onblur="searchBox.OnSearchFieldFocus(false)" 
               onkeyup="searchBox.OnSearchFieldChange(event)"/>
          </span><span class="right">
            <a id="MSearchClose" href="javascript:searchBox.CloseResultsWindow()"><img id="MSearchCloseImg" border="0" src="search/close.png" alt=""/></a>
          </span>
        </div>
      </li>
    </ul>
  </div>
<!-- window showing the filter options -->
<div id="MSearchSelectWindow"
     onmouseover="return searchBox.OnSearchSelectShow()"
     onmouseout="return searchBox.OnSearchSelectHide()"
     onkeydown="return searchBox.OnSearchSelectKey(event)">
<a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(0)"><span class="SelectionMark">&#160;</span>All</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(1)"><span class="SelectionMark">&#160;</span>Classes</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(2)"><span class="SelectionMark">&#160;</span>Functions</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(3)"><span class="SelectionMark">&#160;</span>Variables</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(4)"><span class="SelectionMark">&#160;</span>Groups</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(5)"><span class="SelectionMark">&#160;</span>Pages</a></div>

<!-- iframe showing the search results (closed by default) -->
<div id="MSearchResultsWindow">
<iframe src="javascript:void(0)" frameborder="0" 
        name="MSearchResults" id="MSearchResults">
</iframe>
</div>

</div><!-- top -->
<div class="header">
  <div class="headertitle">
<div class="title">Deputies and Sheriffs </div>  </div>
</div><!--header-->
<div class="contents">
<div class="textblock"><p>This page explains the relationship between deputies and sheriffs, and provides an overview of the communication protocol.</p>
<h2>Deputy - bot-procman-deputy</h2>
<p>A procman deputy is a single process that directly controls user-specified processes. The deputy is responsible for starting commands, stopping commands, and intercepting and transmitting their output (both standard out and standard error). It also reports information on how much CPU and memory each command is using, and can automatically restart commands when they terminate (if requested).</p>
<p>The deputy is essentially a daemon process that manages other commands. It is not interactive, does not have a GUI, and simply carries out orders that it receives from a sheriff.</p>
<h2>Sheriff - bot-procman-sheriff</h2>
<p>The procman sheriff is a process that controls the deputies. The sheriff forms a global view of all deputies and their commands. The sheriff sends commands to the deputies, and specifies which commands a deputy should be managing, and the desired state of those commands.</p>
<p>The sheriff has an interactive GUI through which a user can modify commands and their desired statuses. It also has a scripting facility that can be useful for starting multiple commands at once, sequencing a startup procedure, or running simple scripts in general.</p>
<p>The sheriff can also be run from the command line without a GUI.</p>
<div class="image">
<img src="procman-sheriff-screenshot.png" alt="procman-sheriff-screenshot.png"/>
<div class="caption">
bot-procman-sheriff screenshot</div></div>
 <h3>Observer mode</h3>
<p>A sheriff can be switched to observer mode, where it stops transmitting commands, and simply displays the state of the deputies. Observer mode is useful in situations where you want to simply observe the state of a running system. Examples of this include situations where the active sheriff is running without a GUI, and also when replaying an LCM log file that contains deputy status message (using the LCM log playback tools).</p>
<h2>Communication</h2>
<p>Sheriffs and deputies communicat by transmitting LCM messages to each other. Deputies periodically (1 Hz) transmit their current status, which includes:</p>
<ul>
<li>A listing of each command managed by the deputy and. For each command:<ul>
<li>Whether the command is running</li>
<li>The OS-assigned process ID of the command, if it's running</li>
<li>How much CPU and memory are used by the command</li>
<li>Which group the command is in</li>
</ul>
</li>
</ul>
<p>In addition to the deputy state, each deputy also captures the standard output and standard error for each running command, and transmits the output over LCM.</p>
<p>Sheriffs transmit the desired state for each deputy. For each deputy, the sheriff periodically (1 Hz) transmits a message containing:</p>
<ul>
<li>A listing of all commands the deputy <em>should</em> be managing and the desired state for each command:<ul>
<li>If the command should be running, stopped, or restarted</li>
<li>The program to run, command line arguments, and environment variables.</li>
<li>Which group the command should be in.</li>
<li>If the command should be automatically restarted if/when it terminates.</li>
</ul>
</li>
</ul>
<p>The communications protocol is stateless by design: every message transmitted from a sheriff to the deputy contains the entire desired state of the deputy. Similarly, every message transmitted by a deputy contains its entire internal state. This stateless protocol has a few key features:</p>
<ul>
<li>The entire system is robust to communication dropouts. If a deputy stops receiving messages from the sheriff, the deputy simply continues carrying out its last orders.</li>
<li>When the sheriff starts up, it seamlessly picks up the entire state of the system as it receives updates from each deputy. Deputies are unaffected by a sheriff starting up until the sheriff begins transmitting orders.</li>
<li>A sheriff in observer mode (see above) can pick up the state of the system simply by receiving deputy messages and not transmitting anything. </li>
</ul>
</div></div><!-- contents -->
<!-- start footer part -->
<hr class="footer"/><address class="footer"><small>
Generated on Wed Sep 18 2013 22:30:43 for procman by &#160;<a href="http://www.doxygen.org/index.html">
<img class="footer" src="doxygen.png" alt="doxygen"/>
</a> 1.8.3.1
</small></address>
</body>
</html>
